function
<new>
operator new[]
| throwing (1) | void* operator new[] (std::size_t size) throw (std::bad_alloc); |
|---|
| nothrow (2) | void* operator new[] (std::size_t size, const std::nothrow_t& nothrow_value) throw(); |
|---|
| placement (3) | void* operator new[] (std::size_t size, void* ptr) throw(); |
|---|
| throwing (1) | void* operator new[] (std::size_t size); |
|---|
| nothrow (2) | void* operator new[] (std::size_t size, const std::nothrow_t& nothrow_value) noexcept; |
|---|
| placement (3) | void* operator new[] (std::size_t size, void* ptr) noexcept; |
|---|
Allocate storage space for array
Default allocation functions (array form).
- (1) throwing allocation
-
Allocates size bytes of storage, suitably aligned to represent any object of that size, and returns a non-null pointer to the first byte of this block.
On failure, it throws a bad_alloc exception.
The default definition allocates memory by calling operator new: ::operator new (size).
If replaced, both operator new and operator new[] shall return pointers with identical properties.
- (2) nothrow allocation
-
Same as above (1), except that on failure it returns a null pointer instead of throwing an exception.
The default definition allocates memory by calling the
nothrow version of
operator new:
::operator new (size,nothrow).
If replaced, both
operator new and
operator new[] shall return pointers with identical properties.
The default definition allocates memory by calling the the first version: ::operator new[] (size).
- (3) placement
-
Simply returns ptr (no storage is allocated).
Notice though that, if the function is called by the new expression, the proper initialization will be performed (for class objects, this includes calling its default constructor).
The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:
- Global: All three versions of
operator new are declared in the global namespace, not within the std namespace.
- Implicit: The allocating versions ((1) and (2)) are implicitly declared in every translation unit of a C++ program, no matter whether header
<new> is included or not.
- Replaceable: The allocating versions ((1) and (2)) are also replaceable: A program may provide its own definition that replaces the one provided by default to produce the result described above, or can overload it for specific types.
If set_new_handler has been used to define a new_handler function, this new-handler function is called by the default definitions of the allocating versions ((1) and (2)) if they fail to allocate the requested storage.
operator new[] can be called explicitly as a regular function, but in C++, new[] is an operator with a very specific behavior: An expression with the new operator on an array type, first calls function operator new (i.e., this function) with the size of its array type specifier as first argument (plus any array overhead storage to keep track of the size, if any), and if this is successful, it then automatically initializes or constructs every object in the array (if needed). Finally, the expression evaluates as a pointer to the appropriate type pointing to the first element of the array.
Parameters
- size
- Size in bytes of the requested memory block.
This is, at least, the size of array type specifier in the new expression when called automatically by such an expression (it can be greater, if the the implementation uses additional storage for array types).
If this argument is zero, the function still returns a distinct non-null pointer on success (although dereferencing this pointer leads to undefined behavior).
size_t is an integral type.
- nothrow_value
- The constant nothrow.
This parameter is only used to distinguish it from the first version with an overloaded version. When the nothrow constant is passed as second parameter to operator new[], operator new[] returns a null-pointer on failure instead of throwing a bad_alloc exception.
nothrow_t is the type of constant nothrow.
- ptr
- A pointer to an already-allocated memory block of the proper size.
If called by a new expression, the object is initialized (or constructed) at this location.
Return value
For the first and second versions, a pointer to the newly allocated storage space.
For the third version, ptr is returned.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
// operator new[] example
#include <iostream> // std::cout
#include <new> // ::operator new[]
struct MyClass {
int data;
MyClass() {std::cout << '*';} // print an asterisk for each construction
};
int main () {
std::cout << "constructions (1): ";
// allocates and constructs five objects:
MyClass * p1 = new MyClass[5];
std::cout << '\n';
std::cout << "constructions (2): ";
// allocates and constructs five objects (nothrow):
MyClass * p2 = new (std::nothrow) MyClass[5];
std::cout << '\n';
delete[] p2;
delete[] p1;
return 0;
}
|
Output:
constructions (1): *****
constructions (2): *****
|
Data races
Modifies the storage referenced by the returned value.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.
Exception safety
The first version (1) throws bad_alloc if it fails to allocate storage.
Otherwise, it throws no exceptions (no-throw guarantee).